Skip to content

1.5. Workspace

What defines the workspace contract?

  • README.md gives people the project outcome and quickstart.
  • AGENTS.md gives coding agents layout, conventions, and validation rules.
  • mise.toml defines the commands used locally, by hooks, and in CI.
  • uv.lock and mise.lock pin resolved software.
  • dprint.json, Ruff, ty, pytest, kubeconform, and security tools enforce the boundary.

The repository is the source of truth. Do not copy course snippets into a separate directory and lose the lockfiles, seed data, or task configuration.

How do you prepare a fresh clone?

git clone https://github.com/MLOps-Courses/agentops-open-course.git
cd agentops-open-course
mise install
mise run install
git status --short

The final command should be empty. Generated .venv, .state, site, coverage, and secret files are ignored rather than committed.

Which editor should you use?

Any editor that respects EditorConfig and can run terminal commands works. VSCodium is an open-source distribution of the VS Code codebase; Neovim, Helix, Zed, Emacs, and other editors are equally valid.

Useful integrations are Python language support, Ruff formatting/linting, TOML/YAML schemas, and an EditorConfig client. Editor marketplaces and branded distributions may have separate proprietary terms, so they are optional conveniences rather than course dependencies.

How should a coding agent use AGENTS.md?

The root AGENTS.md explains the repository shape, the docs/source synchronization rule, OSS constraints, commands, and definition of done. A tool should treat it as project guidance, not permission to expose secrets or bypass user approval.

When an agent proposes a change, review the diff and run the same checks you would require from a person. Generated code has no exemption from tests, licensing, or security review.

How do you validate the agent configuration?

Copy the annotated .env.example to .env at the repository root — every variable documents its purpose, default, and which learning path needs it. Then resolve and validate the combination:

mise run config:check

The task loads settings exactly the way every agent entrypoint does (agents/python/src/agent/config.py), prints the effective configuration with secrets masked, and exits non-zero with errors that name the fix. For example, an openai-compatible provider without OPENAI_BASE_URL tells you to choose direct Ollama in Chapters 2-4 or agentgateway in Chapter 5. Re-run it whenever the agent fails at startup after an environment change.

What do the Git hooks enforce?

Lefthook delegates pre-commit and pre-push work to mise. That keeps one command implementation instead of duplicating shell logic in CI and hooks. Hooks are a fast feedback mechanism, not a substitute for running the complete gate before a pull request.

What is the chapter checkpoint?

From the repository root:

mise run format
mise run check:core
mise run test
git status --short

Review any formatting edits, confirm all gates pass without warnings, and ensure only intentional files appear in Git status. This core gate deliberately avoids Docker; the complete mise run check infrastructure gate becomes part of the checkpoint after you install the Chapter 5 container runtime. You are then ready to run and inspect the reference agent in Chapter 2.